Converts a collection object into a stream format suitable for storing and unflattening.

OSErr FlattenCollection (
    Collection c, 
    CollectionFlattenUPP flattenProc, 
    void *refCon
);

c

A reference to the collection that you want to flatten. The behavior of this function is undefined if you do not provide a reference to a valid collection object.

flattenProc

A pointer to a callback function you provide to process the flattened stream of bytes.

refCon

A pointer to the reference constant that you want the Collection Manager to pass to your callback function each time that it calls the callback function. You can use this parameter as a pointer to a structure containing information your callback function needs to process the blocks of flattened data.

function result

A result code. This function can return any error returned by the callback function.

DISCUSSION

You could, for example, use this function to copy a collection onto the Clipboard so that it could be pasted into another application.

The FlattenCollection function flattens into a stream of bytes the collection you specify with the c parameter. As this function flattens the collection, it repeatedly calls the callback function you specify using the flattenProc parameter. Each time it calls this function, it provides the callback function with a pointer to a block of memory containing flattened data. It continues to call this function until it has flattened the entire collection. Your callback function can process the flattened data in a number of ways: it could copy the flattened data into a handle-based block of memory, it could write the flattened data to disk, and so on.

When flattening the c collection, this function includes only the collection items whose persistence attribute is set.

To create a flattened collection that includes only those collection items whose attributes match a specified pattern, use the FlattenPartialCollection function.

To unflatten a flattened collection, use the UnflattenCollection function.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.

© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)